<html xmlns="http://www.w3.org/1999/xhtml">
   <head>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
      <title>2. Using Piperack</title>
      <meta charset="utf-8" />
      <meta name="generator" content="DocBook XSL 2.0 Stylesheets V2.5.0" />
      <link href="css/default.css" rel="stylesheet" type="text/css" />
      <link href="css/db-prism.css" rel="stylesheet" type="text/css" />
      <link rel="stylesheet" href="css/xproc.css" type="text/css" /><script type="text/javascript" src="js/dbmodnizr.js"></script></head>
   <body>
      <div class="page">
         <div class="content">
            <div xmlns:tmpl="http://docbook.org/xslt/titlepage-templates" class="navheader">
               <table border="0" cellpadding="0" cellspacing="0" width="100%" summary="Navigation table">
                  <tr>
                     <td align="left"> <a title="XML Calabash Reference" href="index.html"><img src="img/home.png" alt="Home" border="0" /></a> <a href="runpiperack.html" title="1 .  Running Piperack"><img src="img/prev.png" alt="Prev" border="0" /></a> <a title="Chapter  6 .  Piperack" href="piperack.html"><img src="img/up.png" alt="Up" border="0" /></a> <a title="Standard XProc Steps" href="p-steps.html"><img src="img/next.png" alt="Next" border="0" /></a></td>
                     <td align="right"><i>XML Calabash Reference</i> (Version 0.28)</td>
                  </tr>
               </table>
            </div>
            <div class="body">
               <section id="using-piperack" class="section">
                  <div class="section-titlepage">
                     <h2>2. Using Piperack</h2>
                  </div>
                  <div class="content">
                     <p>Running pipelines with <span class="application">Piperack</span> is
                        performed through a RESTful web services API. The examples that follow
                        use <span class="application">curl</span>, but any tool that supports the ability to
                        GET and POST resources to a web service will work.</p>
                     <div class="important admonition">
                        <h3>Important</h3>
                        <div class="admonition-body">
                           <p>When running, <span class="application">Piperack</span> has all of the
                              privileges of the user who started it. Just because you <em>could</em>
                              allow the public to access it, doesn't mean you should. Your gun, your bullet,
                              your foot.</p>
                        </div>
                     </div>
                     <p>When started, <span class="application">Piperack</span> listens for requests
                        on the configured port. In the examples that follow, it is running on
                        “<code class="literal">localhost</code>” on port “<code class="literal">8088</code>”. If you're running
                        it on a different machine or port, adjust the examples accordingly.</p>
                     <p>For most endpoints, content negotiation is used to determine how the
                        results should be returned. XML, HTML, plain text, and JSON are all supported.
                        Endpoints that return the outputs of a pipeline after it has been run
                        always return XML.</p>
                     <p>Our example pipeline for this section is <code class="filename">pipe.xpl</code>:</p>
                     <pre class="programlisting language-none line-numbers"><code>&lt;p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
                xmlns:ex="http://example.com/ns/example"
                name="main" version="1.0" exclude-inline-prefixes="ex"&gt;
   &lt;p:input port="source" sequence="true"/&gt;
   &lt;p:input port="parameters" kind="parameter"/&gt;
   &lt;p:output port="result" sequence="true" primary="true"/&gt;
   &lt;p:output port="result2" sequence="true"&gt;
     &lt;p:pipe step="id" port="result"/&gt;
   &lt;/p:output&gt;
   &lt;p:option name="opt1" select="'default'"/&gt;
   &lt;p:option name="ex:opt2" select="'default'"/&gt;
   &lt;p:serialization port="result" indent="true"/&gt;

   &lt;p:identity name="id"/&gt;
&lt;/p:declare-step&gt;</code></pre>
                     <p>It doesn't do anything useful, it simply copies its input to two different
                        output ports.</p>
                     <section id="pr-status" class="section">
                        <div class="section-titlepage">
                           <h3>2.1. <code class="uri">/status</code></h3>
                        </div>
                        <div class="content">
                           <p>The <code class="uri">/status</code> endpoint just returns information about the
                              status of the server. Only GET is supported.</p>
                           <pre class="screen language-none line-numbers"><code><code class="prompt">$ </code><strong class="userinput"><code>curl -H "Accept: text/plain" http://localhost:8088/status</code></strong>
<code class="computeroutput">XML Calabash version 1.0.14a, an XProc processor.
Running on Saxon version 9.5.1.1, EE edition.
Copyright © 2007-2013 Norman Walsh
See docs/notices/NOTICES in the distribution for licensing.
See also http://xmlcalabash.com/ for more information.</code></code></pre>
                        </div>
                     </section>
                     <section id="pr-help" class="section">
                        <div class="section-titlepage">
                           <h3>2.2. <code class="uri">/help</code> (or just <code class="uri">/</code>)</h3>
                        </div>
                        <div class="content">
                           <p>The <code class="uri">/help</code> endpoint returns a summary of the valid endpoints
                              only GET is supported.</p>
                        </div>
                     </section>
                     <section id="pr-pipelines" class="section">
                        <div class="section-titlepage">
                           <h3>2.3. <code class="uri">/pipelines</code></h3>
                        </div>
                        <div class="content">
                           <p>A new pipeline is added to the server by POSTing it to the
                              <code class="uri">/pipelines</code> endpoint. The user can suggest an ID with the
                              <em class="parameter"><code>name</code></em> parameter. (If the requested name is in use,
                              a different, unique name will be returned.)</p>
                           <pre class="screen language-none line-numbers"><code><code class="prompt">$ </code><strong class="userinput"><code>curl -X POST -d@pipe.xpl http://localhost:8088/pipelines?name=mypipe</code></strong>
<code class="computeroutput">&lt;response xmlns="http://xmlcalabash.com/ns/piperack"&gt;
   &lt;code&gt;201&lt;/code&gt;
   &lt;expires&gt;2013-10-25T15:49:04Z&lt;/expires&gt;
   &lt;uri&gt;http://localhost:8088/pipelines/mypipe&lt;/uri&gt;
   &lt;message&gt;Created http://localhost:8088/pipelines/mypipe&lt;/message&gt;
&lt;/response&gt;</code></code></pre>
                           <p>The response also includes the HTTP Location header, pointing to the
                              newly minted URI for the pipeline.</p>
                           <p>All pipelines get an expiration time when they are created. Periodically,
                              the server will delete any pipelines that are past their expiration time.</p>
                           <p>The default expiration time can be set in several ways, see
                              <a href="cfg.piperack.html" title="Piperack configuration">Section 34, “Piperack configuration”</a>. The <em class="parameter"><code>expires</code></em> parameter
                              can be used to specify a different expiration time for any particular pipeline
                              when it is created. If -1 is specified, the pipeline will never expire.</p>
                           <p>Performing a GET on <code class="uri">/pipelines</code> returns a list of the pipelines
                              available.</p>
                           <pre class="screen language-none"><code><code class="prompt">$ </code><strong class="userinput"><code>curl -H "Accept: application/json" http://localhost:8088/pipelines</code></strong>
<code class="computeroutput">{"pipelines":["http://localhost:8088/pipelines/mypipe"]}</code></code></pre>
                        </div>
                     </section>
                     <section id="pr-pipelines-id" class="section">
                        <div class="section-titlepage">
                           <h3>2.4. <code class="uri">/pipelines/{id}</code></h3>
                        </div>
                        <div class="content">
                           <p>Performing a GET on <code class="uri">/pipelines/{id}</code> returns information
                              about the pipeline:</p>
                           <pre class="screen language-none line-numbers"><code><code class="prompt">$ </code><strong class="userinput"><code>curl http://localhost:8088/pipelines/mypipe</code></strong>
<code class="computeroutput">&lt;pipeline xmlns="http://xmlcalabash.com/ns/piperack"&gt;
   &lt;uri&gt;http://localhost:8088/pipelines/mypipe&lt;/uri&gt;
   &lt;has-run&gt;false&lt;/has-run&gt;
   &lt;input documents="0"&gt;source&lt;/input&gt;
   &lt;input primary="true" documents="0"&gt;parameters&lt;/input&gt;
   &lt;option&gt;
      &lt;name&gt;opt1&lt;/name&gt;
      &lt;value default="true"/&gt;
   &lt;/option&gt;
   &lt;option&gt;
      &lt;name xmlns:ex="http://example.com/ns/example"&gt;ex:opt2&lt;/name&gt;
      &lt;value default="true"/&gt;
   &lt;/option&gt;
&lt;/pipeline&gt;</code></code></pre>
                           <p>The exact information returned varies depending on the state of the pipeline
                              (before or after it has been run) and on the state of the various inputs, outputs,
                              options, and parameters.</p>
                           <p>As we shall see, there are individual endpoints for sending documents to the
                              pipeline, setting options, setting parameters, and running the pipeline. However,
                              you can post
                              directly to the pipeline URI.</p>
                           <p>POSTing <code class="code">multipart/form-data</code> according to RFC 2388
                              to <code class="uri">/pipelines/{id}</code> has the following effects:</p>
                           <div class="orderedlist">
                              <ol style="list-style: decimal;">
                                 <li>
                                    <p>Each uploaded document is delievered to the named input port.
                                       It is an error if the pipeline has no such port.</p>
                                 </li>
                                 <li>
                                    <p>Any POSTed data that isn't an uploaded document is treated as
                                       the value of a named option or parameter.</p>
                                 </li>
                              </ol>
                           </div>
                           <p>POSTing a single document to <code class="uri">/pipelines/{id}</code> has the
                              following effects:</p>
                           <div class="orderedlist">
                              <ol style="list-style: decimal;">
                                 <li>
                                    <p>The POSTed document is delivered to the pipeline's primary input port.
                                       It is an error if the pipeline does not have a primary input port.</p>
                                 </li>
                                 <li>
                                    <p>Any parameters passed as part of the URI are delivered to the pipeline
                                       as the values of named options or parameters.</p>
                                 </li>
                              </ol>
                           </div>
                           <p>By default simple <em class="replaceable"><code>name=value</code></em> pairs posted
                              to the pipeline are treated as named options.
                              To specify a parameter, use a
                              name of the form <code class="literal">-pparameter-name</code>. By default
                              the parameter will be written to the primary parameter input port.
                              To specify a particular port explicitly, use a field name of the form
                              <code class="literal">-pport@parameter-name</code>.</p>
                           <p>Use fields of the form
                              <code class="code">xmlns:<em class="replaceable"><code>prefix</code></em></code> to specify namespace bindings,
                              if necessary.</p>
                           <p>After the POSTed data is processed, the pipeline is run.</p>
                           <p>If the pipeline runs successfully, the first document on the pipeline's
                              primary output port is returned. If the pipeline has no primary output port,
                              nothing is returned.</p>
                           <p>For example:</p>
                           <pre class="screen language-none"><code><code class="prompt">$ </code><strong class="userinput"><code>curl -X POST -F "source=@doc.xml;type=application/xml" -F "opt1=somevalue" http://localhost:8088/pipelines/mypipe</code></strong>
<code class="computeroutput">&lt;doc/&gt;</code></code></pre>
                           <p>Or</p>
                           <pre class="screen language-none"><code><code class="prompt">$ </code><strong class="userinput"><code>curl -X POST -H "Content-type: application/xml" -d @doc.xml "http://localhost:8088/pipelines/mypipe&amp;opt1=somevalue"</code></strong>
<code class="computeroutput">&lt;doc/&gt;</code></code></pre>
                        </div>
                     </section>
                     <section id="pr-pipelines-id-inputs-port" class="section">
                        <div class="section-titlepage">
                           <h3>2.5. <code class="uri">/pipelines/{id}/inputs/{port}</code></h3>
                        </div>
                        <div class="content">
                           <p>POSTing to <code class="uri">/pipelines/{id}/inputs/{port}</code> delivers the POSTed
                              document to the specified port.</p>
                        </div>
                     </section>
                     <section id="pr-piplines-id-options" class="section">
                        <div class="section-titlepage">
                           <h3>2.6. <code class="uri">/pipelines/{id}/options</code></h3>
                        </div>
                        <div class="content">
                           <p>POSTing to <code class="uri">/pipelines/{id}/options</code> delivers the POSTed
                              parameters (from the <code class="literal">application/x-www-form-urlencoded</code>
                              body or from the URI) to the pipeline as options.</p>
                           <pre class="screen language-none line-numbers"><code><code class="prompt">$ </code><strong class="userinput"><code>curl -X POST "http://localhost:8088/pipelines/mypipe/options?xmlns:x=http://example.com/ns/example&amp;x:opt2=two&amp;opt1=one"</code></strong>
<code class="computeroutput">&lt;response xmlns="http://xmlcalabash.com/ns/piperack"&gt;
   &lt;code&gt;202&lt;/code&gt;
   &lt;message&gt;Options added: opt1, x:opt2&lt;/message&gt;
&lt;/response&gt;</code></code></pre>
                           <p>The pipeline information endpoint will now show that those values have
                              been specified.</p>
                           <pre class="screen language-none line-numbers"><code><code class="prompt">$ </code><strong class="userinput"><code>curl http://localhost:8088/pipelines/mypipe</code></strong>
<code class="computeroutput">&lt;pipeline xmlns="http://xmlcalabash.com/ns/piperack"&gt;
   &lt;uri&gt;http://localhost:8088/pipelines/mypipe&lt;/uri&gt;
   &lt;has-run&gt;false&lt;/has-run&gt;
   &lt;input primary="true" documents="0"&gt;source&lt;/input&gt;
   &lt;input documents="0"&gt;parameters&lt;/input&gt;
   &lt;option&gt;
      &lt;name&gt;opt1&lt;/name&gt;
      &lt;value&gt;one&lt;/value&gt;
   &lt;/option&gt;
   &lt;option&gt;
      &lt;name xmlns:ex="http://example.com/ns/example"&gt;ex:opt2&lt;/name&gt;
      &lt;value&gt;two&lt;/value&gt;
   &lt;/option&gt;
&lt;/pipeline&gt;</code></code></pre>
                        </div>
                     </section>
                     <section id="pr-pipelines-id-options-option" class="section">
                        <div class="section-titlepage">
                           <h3>2.7. <code class="uri">/pipelines/{id}/options/{option}</code></h3>
                        </div>
                        <div class="content">
                           <p>POSTing to <code class="uri">/pipelines/{id}/options/{option}</code> sets the value
                              of the option named “<em class="replaceable"><code>{option}</code></em>” to the POSTed
                              content. This option exists to support the “general values” extension; it's
                              otherwise not necessary.</p>
                           <p>If the option name is in a namespace, use a parameter of the form
                              <code class="code">xmlns:<em class="replaceable"><code>prefix</code></em></code> on the URI to specify
                              the namespace binding.</p>
                        </div>
                     </section>
                     <section id="pr-pipelines-id-parameters" class="section">
                        <div class="section-titlepage">
                           <h3>2.8. <code class="uri">/pipelines/{id}/parameters</code></h3>
                        </div>
                        <div class="content">
                           <p>POSTing to <code class="uri">/pipelines/{id}/parameters</code> delivers the POSTed
                              parameters (from the <code class="literal">application/x-www-form-urlencoded</code>
                              body or from the URI) to the pipeline as parameters.</p>
                           <p>This endpoint uses the primary parameter input port.</p>
                        </div>
                     </section>
                     <section id="pr-pipelines-id-parameters-port" class="section">
                        <div class="section-titlepage">
                           <h3>2.9. <code class="uri">/pipelines/{id}/parameters/{port}</code></h3>
                        </div>
                        <div class="content">
                           <p>POSTing to <code class="uri">/pipelines/{id}/parameters/{port}</code> delivers the POSTed
                              parameters (from the <code class="literal">application/x-www-form-urlencoded</code>
                              body or from the URI) to the pipeline as parameters on the
                              “<em class="replaceable"><code>{port}</code></em>” parameter input port.</p>
                        </div>
                     </section>
                     <section id="pr-pipelines-id-parameters-port-param" class="section">
                        <div class="section-titlepage">
                           <h3>2.10. <code class="uri">/pipelines/{id}/parameters/{port}/{param}</code></h3>
                        </div>
                        <div class="content">
                           <p>POSTing to <code class="uri">/pipelines/{id}/parameters/{port}/{param}</code> sets the value
                              of the option named “<em class="replaceable"><code>{param}</code></em>” to the POSTed
                              content. This option exists to support the “general values” extension; it's
                              otherwise not necessary.</p>
                           <p>If the parameter name is in a namespace, use a parameter of the form
                              <code class="code">xmlns:<em class="replaceable"><code>prefix</code></em></code> on the URI to specify
                              the namespace binding.</p>
                        </div>
                     </section>
                     <section id="pr-pipelines-id-run" class="section">
                        <div class="section-titlepage">
                           <h3>2.11. <code class="uri">/pipelines/{id}/run</code></h3>
                        </div>
                        <div class="content">
                           <p>POSTing to the <code class="uri">/pipelines/{id}/run</code> endpoint runs
                              the pipeline and returns the first document on the primary output port.</p>
                           <p>The pipeline information endpoint will now show outputs instead of
                              inputs.</p>
                           <pre class="screen language-none line-numbers"><code><code class="prompt">$ </code><strong class="userinput"><code>curl http://localhost:8088/pipelines/mypipe</code></strong>
<code class="computeroutput">&lt;pipeline xmlns="http://xmlcalabash.com/ns/piperack"&gt;
   &lt;uri&gt;http://localhost:8088/pipelines/mypipe&lt;/uri&gt;
   &lt;has-run&gt;true&lt;/has-run&gt;
   &lt;output primary="true" documents="0"&gt;result&lt;/output&gt;
   &lt;output documents="1"&gt;result2&lt;/output&gt;
&lt;/pipeline&gt;</code></code></pre>
                        </div>
                     </section>
                     <section id="pr-pipelines-id-outputs-port" class="section">
                        <div class="section-titlepage">
                           <h3>2.12. <code class="uri">/pipelines/{id}/outputs/{port}</code></h3>
                        </div>
                        <div class="content">
                           <p>After a pipeline has been run, a GET request to
                              <code class="uri">/pipelines/{id}/outputs/{port}</code> returns the next document
                              from the specified port.</p>
                           <pre class="screen language-none"><code><code class="prompt">$ </code><strong class="userinput"><code>curl http://localhost:8088/pipelines/mypipe/outputs/result2</code></strong>
<code class="computeroutput">&lt;doc/&gt;</code></code></pre>
                        </div>
                     </section>
                     <section id="pr-pipelines-id-reset" class="section">
                        <div class="section-titlepage">
                           <h3>2.13. <code class="uri">/pipelines/{id}/reset</code></h3>
                        </div>
                        <div class="content">
                           <p>POSTing to <code class="uri">/pipelines/{id}/reset</code> resets the pipeline: deletes
                              all inputs, outputs, options, and parameters.</p>
                        </div>
                     </section>
                     <section id="pr-stop" class="section">
                        <div class="section-titlepage">
                           <h3>2.14. <code class="uri">/stop</code></h3>
                        </div>
                        <div class="content">
                           <p>POSTing to <code class="uri">/stop</code> stops <span class="application">Piperack</span>.</p>
                        </div>
                     </section>
                  </div>
               </section>
            </div>
         </div>
         <div xmlns:tmpl="http://docbook.org/xslt/titlepage-templates" class="navfooter">
            <table width="100%" summary="Navigation table">
               <tr>
                  <td width="40%" align="left"><a title="1 .  Running Piperack" href="runpiperack.html"><img src="img/prev.png" alt="Prev" border="0" /></a> </td>
                  <td width="20%" align="center"><a title="XML Calabash Reference" href="index.html"><img src="img/home.png" alt="Home" border="0" /></a></td>
                  <td width="40%" align="right"> <a title="Standard XProc Steps" href="p-steps.html"><img src="img/next.png" alt="Next" border="0" /></a></td>
               </tr>
               <tr>
                  <td width="40%" align="left">1 .  Running Piperack </td>
                  <td width="20%" align="center"><a title="Chapter  6 .  Piperack" href="piperack.html"><img src="img/up.png" alt="Up" border="0" /></a></td>
                  <td width="40%" align="right"> Standard XProc Steps</td>
               </tr>
            </table>
         </div>
         <div xmlns:tmpl="http://docbook.org/xslt/titlepage-templates" class="copyrightfooter">
            <p><a href="dbcpyright.html">Copyright</a> © 2011–2020 Norman Walsh.</p>
         </div>
      </div>
   </body>
</html>